2. EL 6 ELS
  3. man-pages-pl
  4. man(7)

Scroll to navigation

MAN(7) Podręcznik linuksowego programisty MAN(7)

NAZWA

man - makra do formatowania stron man

SKŁADNIA

groff -Tascii -man plik ...

groff -Tps -man plik ...

man [sekcja] tytuł

OPIS

Ta strona podręcznika opisuje pakiet makr groff tmac.an . Pakiet tych makr powinien być używany przez developerów kiedy piszą lub przenoszą strony man dla Linuksa. Jest on w pełni kompatybilny z innymi wersjami tego pakietu, więc przenoszenie stron nie powinno być głównym problemem (wyjątki włączają NET-2 BSD, które używa całkiem innego pakietu makr).

Zauważ, że strony NET-2 BSD mogą być użyte z groffem przez proste podanie opcji -mdoc zamiast zwykłej -man . Używanie opcji -mandoc jest jednak bardziej zalecane, jako że wybierze ona automatycznie odpowiedni zestaw makr.

PREAMBUŁA

Pierwszą komendą na stronie man powinna być

.TH title section date source manual,

gdzie:
Tytuł strony podręcznika (np. MAN).
Numer sekcji, w której strona powinna się znaleźć (np. 7).
Data ostatniego poprawienia—pamiętaj, by zmieniać ją za każdym razem, kiedy dokonasz zmiany na stronie, ponieważ jest to najpopularniejsza droga kontrolowania wersji.
Źródło komendy.

Dla binariów używaj czegoś w rodzaju: GNU, NET-2, SLS Distribution, MCC Distribution.

Dla wywołań systemowych, używaj wersji jądra, której używasz: Linux 0.99.11.

Dla wywołań bibliotecznych, użyj źródła funkcji: GNU, BSD 4.3, Linux DLL 4.4.1.

Tytuł podręcznika (np. Linux Programmer's Manual).

Sekcje podręcznika man są tradycyjnie definiowane następująco:

1 Komendy
Te komendy mogą być wykonywane przez użytkownika z powłoki.
2 Wywołania systemowe
Te funkcje muszą być obsługiwane przez jądro.
3 Wywołania biblioteczne
Większość funkcji libc takich jak sort(3))
4 Pliki specjalne
Pliki, które można znaleźć w /dev)
5 Formaty plików i konwencje
Format dla pliku /etc/passwd i innych nadających się do odczytu przez człowieka.
6 Gry
7 Pakiety makr i konwencje
Opis standardowego rozkładu systemu plików, ta strona podręcznika i wiele innych rzeczy.
8 Komendy zarządzania systemem.
Komendy takie, jak mount(8), które wywoływać może tylko root .
9 Wywołania jądra
Jest to niestandardowa sekcja podręcznika i jest włączona ponieważ źródła jądra Linuksa są swobodnie rozpowszechniane z licencją GPL i wielu ludzi pracuje nad zmianami jądra.

FONTY

Chociaż istnieje wiele konwencji dla stron man w świecie Unixowym, istnienie setek stron specyficznych Linuksowi definiuje nasze standardy:

Dla funkcji, argumenty zawsze są podawane kursywą, nawet w sekcji SKŁADNIA, gdzie reszta funkcji jest wydrukowana w pogrubieniu:
int myfunction(int argc, char **argv);
Nazwy plików są także zawsze pisane kursywą (np. /usr/include/stdio.h), poza tymi z sekcji SKŁADNIA, gdzie włączane pliki są pogrubione (np. #include <stdio.h>).
Makra specjalne, które są zwykle pisane dużymi literami, są pogrubiane (np. MAXINT).
Podczas enumerowania listy kodów błędów, kody są pogrubiane (taka lista zwykle używa makra .TP ).
Wszelkie odwołania do innych stron man (lub temat bieżącej strony) są pogrubione. Jeśli podany jest numer sekcji podręcznika, podany jest bez spacji fontem roman, (np. man(7)).

Komendy do wyboru czcionki są podane niżej:

.B
Pogrubienie
.BI
Pogrubienie naprzemiennie z kursywą
.BR
Pogrubienie naprzemiennie z fontem roman
.I
Kursywa
.IB
Kursywa naprzemiennie z pogrubieniem
.IR
Kursywa naprzemiennie z fontem roman
.RB
Font roman naprzemiennie z pogrubieniem
.RI
Font roman naprzemiennie z kursywą
.SB
Mały font naprzemiennie z pogrubieniem
.SM
Mały font

Tradycyjnie, każda komenda może mieć do sześciu argumentów, lecz wersja GNU wydaje się znosić to ograniczenie. Argumenty są oddzielane spacjami. Podwójne cudzysłowy mogą być używane do określania argumentów ze spacjami. Wszystkie argumenty zostaną wydrukowane obok siebie, bez wtrąconych spacji, tak że komenda .BR może zostać użyta do podania słowa pogrubionego, po którym następuje znak interpunkcyjny w foncie roman.

SEKCJE

Sekcje zaczynają się od .SH, po którym występuje nazwa. Jeśli nazwa zawiera spacje i pojawia się w tej samej linii co .SH, to umieść ją między podwójnymi cudzysłowami. Tradycyjne nagłówki to: NAZWA, SKŁADNIA, OPIS, OPCJE, PLIKI, ZOBACZ TAKŻE, DIAGNOSTYKA, BŁĘDY, i AUTOR. Jedynym wymaganym nagłówkiem jest NAZWA, po którym powinna nastąpić linijka z opisem programu:

.SH NAZWA
chess \- gra w szachy

Jest niesamowicie ważnym, aby używać tego formatu i że występuje backshlash przed kreską po nazwie komendy. Ta składnia (angielska, gdzie NAZWA to NAME) jest wykorzystywana przez program makewhatis(8) do tworzenia bazy krótkich opisów komend dla programu whatis(1) i apropos(1).

INNE MAKRA

Inne makra to między innymi:

.DT
Domyślne tabulacje
.HP
Początek wiszącego wcięcia
.IP
Rozpocznij akapit wiszącym tagiem. Jest to to samo co .TP, poza tym, że tag podany jest w tej samej linii, nie w następnej.
.LP
To samo co .PP
.PD
Ustaw odstęp międzyakapitowy na argument
.PP
Rozpocznij nowy akapit
.RE
Zakończ relatywne wcięcie (wcinany akapit)
.RS
Rozpocznij relatywne wcięcie (wcinany akapit)
.SS

Pod-nagłówek (jak .SH, lecz używane do podsekcji)

.TP
Rozpocznij akapit z wiszącym tagiem. Tag jest podawany w następnej linii. Jest to podobne do .IP

PLIKI

/usr/local/lib/groff/tmac/tmac.an
/usr/man/whatis

ZOBACZ TAKŻE

groff(1), man(1), whatis(1), apropos(1), makewhatis(8)

25 July 1993 Linux